<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Throw</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Throw <span class="ver">[v1.1.04+]</span></h1>

<p>Signals the occurrence of an error. This signal can be caught by a <a href="Try.htm">try</a>-<a href="Catch.htm">catch</a> statement.</p>

<pre class="Syntax">Throw [, Expression]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Expression</dt>
  <dd><p>A value to store in <a href="Catch.htm">catch</a>'s OutputVar.</p>
      <p>Since this parameter is an <a href="../Variables.htm#Expressions">expression</a>, all of the following are valid examples:</p>
<pre>throw 3
throw &quot;literal string&quot;
throw MyVar
throw i + 1
throw { what: &quot;Custom error&quot;, file: A_LineFile, line: A_LineNumber } <em>; Throws an <a href="../objects/Object.htm">object</a></em></pre>
<p>This parameter is always an expression, so variable references should not be enclosed in <a href="../FAQ.htm#percent">percent signs</a> except to perform a <a href="../Variables.htm#ref">double-deref</a>.</p>
<p><span class="ver">[v1.1.05+]:</span> If omitted, an <a href="#Exception">exception object</a> is thrown with a default message.</p></dd>

</dl>

<h3 id="Exception">Exception(Message [, What, Extra])</h3>
<p>Creates an object with the following properties, also common to exceptions created by <a href="Catch.htm#RuntimeErrors">runtime errors</a>:</p>
<ul>
  <li><strong>Message:</strong> An error message or <a href="../misc/ErrorLevel.htm">ErrorLevel</a> value.</li>
  <li><strong>What:</strong> The name of the command, function or label which was executing or about to execute when the error occurred.</li>
  <li><strong>Extra:</strong> Additional information about the error, if available.</li>
  <li><strong>File:</strong> Set automatically to the full path of the script file which contains the line at which the error occurred.</li>
  <li><strong>Line:</strong> Set automatically to the line number at which the error occurred.</li>
</ul>
<p>If <em>What</em> is omitted, it defaults to the name of the current function or subroutine. Otherwise it can be a string or a negative offset from the top of the call stack. For example, a value of -1 sets <code>Exception.What</code> to the current function or subroutine and <code>Exception.Line</code> to the line which called it. However, if the script is <a href="../Scripts.htm#ahk2exe">compiled</a> or the offset is invalid, <em>What</em> is simply converted to a string.</p>
<p><em>Message</em> and <em>Extra</em> are converted to strings. These are displayed by an error dialog if the exception is thrown and not caught.</p>
<pre>try
    BadlyCodedFunc()
catch e
    MsgBox % "Error in " e.What ", which was called at line " e.Line 

BadlyCodedFunc() {
    throw Exception("Fail", -1)
}</pre>

<h3>Related</h3>
<p><a href="Try.htm">Try</a>, <a href="Catch.htm">Catch</a>, <a href="Finally.htm">Finally</a></p>
<h3>Examples</h3>
<p>See <a href="Try.htm#Examples">Try</a>.</p>

</body>
</html>
